Design Docs

what?

「Google で必ず書くことになっているドキュメント」であり、「プロジェクト立ち上げ時の 1～2週間をかけて書く」ものです

ソフトウェアシステムやアプリケーションの作成者が、コーディングに着手する前に作成する比較的形式ばらないドキュメントです。

デザインドキュメントは、ソフトウェア設計でのトレードオフを書き留める場所です。

文脈と範囲

どういうシチュで何をつくろうとしているのか

読者にイメージをつかませる

目標と非目標

要件ともいう

非目標はdo notではなくトレードオフ可能な形で書くと良い

理的に目標である可能性があるものの、明示的に目標ではないことが選択されていることに注意してください。 良い例は「ACID」(*1)です。 データベースを設計するときは、それが目標か非目標かを確実に知りたいでしょう。 そして、それが非目標であっても、目標の達成を妨げるトレードオフが発生しなければ、それを提供する解決策を選択することかもしれません。

実際のデザイン

システムコンテキスト図

特に「ここであつかってるシステムは、全体で言えばこの辺だぜ」を示す

API

コピー＆ペーストをしたくなる誘惑には耐える必要があります。その代わりに、設計とのトレードオフに関連する部分に焦点を当ててください。

データストレージ

データを保存するシステムでは、いつ、どのような形で発生するのかを議論すべきでしょう。

コードは基本的に含まれないはず

だが必要ならプロトへのリンクを入れても良い

制約の度合い

制約を列挙しておく

考慮された代替案

他の案も考えられる場合になぜそれを採用しなかったかを書く

横断的な懸念事項

キュリティ、プライバシー、観察可能性などの領域横断的な懸念事項が常に考慮されていることを確認することができます。これらの多くは、設計がどのように懸念事項に影響を与えるか、また、懸念事項にどのように対処するかを説明する比較的短いセクションです。

事実上、別のドキュメントとレビューに投げる形になってるみたい

長さ

10～20 or それ以下

大きなプロジェクトでは約10〜20ページです。それ以上になると、問題をより管理しやすい単位に分割する方が理にかなっています。また、1〜3ページの「ミニデザインドキュメント」を書くことも可能です。

アジャイルと同じで「特定の目的を満たせる小さなドキュメント」をつくるべき

この design docs もその一つにすぎない

書かなくてもいいとき

ドキュメント書くオーバーヘッドに見合わないとき

トップダウンで「いいからこのとおりにしろ」 or 特に技術的問題もなくてそのとおりでよいとき（さっさと実装しなさい）

ライフサイクル

アジャイルにぐるぐる回しながらつくってく

レビューは回覧メインで、どっかで上級エンジニア交えた正式なのも入れる

が、レビューはコスト高いので程々に

設計書はちゃんと更新した方がいいです

逃げがちだけど

以下のqに3つ以上当てはまるなら、たぶんdesign docsは有意義

適切なソフトウェア設計に確信が持てず、確実性を得るために事前調査に時間をかけることに意味があると言えますか？

関連して、すべてのコード変更をレビューすることができない可能性のある上級アエンジニアを設計に参加させるのに役立ちそうでしょうか？

ソフトウェア設計が曖昧であったり、あるいは議論の余地があったりして、組織的な合意を得ることがプロジェクトでは重要になりそうでしょうか？

私のチームは、プライバシー、セキュリティ、ロギング、その他の横断的な懸念事項を設計の中で考慮することを忘れてしまうことがありますか？

組織内のレガシーシステムの設計について高レベルな洞察を提供するドキュメントの必要性が強く求められていますか？

sta.icon

ちょうど仕事でまさに設計するところなので、使ってみたいな

適切なソフトウェア設計に確信が持てず、確実性を得るために事前調査に時間をかけることに意味があると言えますか？

y

関連して、すべてのコード変更をレビューすることができない可能性のある上級アエンジニアを設計に参加させるのに役立ちそうでしょうか？

y

ソフトウェア設計が曖昧であったり、あるいは議論の余地があったりして、組織的な合意を得ることがプロジェクトでは重要になりそうでしょうか？

y……？

私のチームは、プライバシー、セキュリティ、ロギング、その他の横断的な懸念事項を設計の中で考慮することを忘れてしまうことがありますか？

y

組織内のレガシーシステムの設計について高レベルな洞察を提供するドキュメントの必要性が強く求められていますか？

n